/*
 * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.nio.channels;

import java.io.IOException;
import java.nio.ByteBuffer;


/**
 * 一种可以从缓冲区序列中写入字节的通道。
 *
 * <p> 在一次调用中，收集写操作从一个或多个给定的缓冲区序列中写入字节。
 * 在实现网络协议或文件格式时，收集写操作通常很有用，
 * 例如，将数据分组到由一个或多个固定长度的头和可变长度的主体组成的段中。
 * 在ScatteringByteChannel接口中定义了类似的散射读取操作。</p>
 *
 *
 * @author Mark Reinhold
 * @author JSR-51 Expert Group
 * @since 1.4
 */

public interface GatheringByteChannel
    extends WritableByteChannel
{

    /**
     * 从给定缓冲区的子序列中写入一个字节序列到该通道。
     *
     * <p> 尝试向该通道写入最多r个字节，其中r是给定缓冲区数组的指定子序列中剩余的总字节数，即，
     *
     * <blockquote><pre>
     * srcs[offset].remaining()
     *     + srcs[offset+1].remaining()
     *     + ... + srcs[offset+length-1].remaining()</pre></blockquote>
     *
     * at the moment that this method is invoked.
     *
     * <p> 假设一个字节序列长度n是写,其中0 < = n < = r 。
     * 从srcs[offset]，最多写入srcs[offset].remaining()字节缓冲区的字节序列，
     * 从srcs[offset+1]，最多写入srcs[offset+1].remaining()字节缓冲区的字节序列，等等,直到整个字节序列经。
     * 从每个缓冲区写入尽可能多的字节，因此，每个更新缓冲区的最终位置，除了最后一个更新缓冲区，保证等于该缓冲区的限制。
     *
     * <p> 除非另有规定，写操作只会在写完所有r个请求的字节后返回。
     * 某些类型的通道，取决于它们的状态，可能只写一些字节，也可能根本不写。
     * 例如，在非阻塞模式下的套接字通道不能发送比套接字输出缓冲区中空闲的字节更多的字节。
     *
     * <p> 此方法可以在任何时候调用。
     * 但是，如果另一个线程已经在这个通道上启动了写操作，那么对这个方法的调用将阻塞，直到第一个操作完成。 </p>
     *
     * @param  srcs
     *         The buffers from which bytes are to be retrieved
     *
     * @param  offset
     *         The offset within the buffer array of the first buffer from
     *         which bytes are to be retrieved; must be non-negative and no
     *         larger than <tt>srcs.length</tt>
     *
     * @param  length
     *         The maximum number of buffers to be accessed; must be
     *         non-negative and no larger than
     *         <tt>srcs.length</tt>&nbsp;-&nbsp;<tt>offset</tt>
     *
     * @return  The number of bytes written, possibly zero
     *
     * @throws  IndexOutOfBoundsException
     *          If the preconditions on the <tt>offset</tt> and <tt>length</tt>
     *          parameters do not hold
     *
     * @throws  NonWritableChannelException
     *          If this channel was not opened for writing
     *
     * @throws  ClosedChannelException
     *          If this channel is closed
     *
     * @throws  AsynchronousCloseException
     *          If another thread closes this channel
     *          while the write operation is in progress
     *
     * @throws  ClosedByInterruptException
     *          If another thread interrupts the current thread
     *          while the write operation is in progress, thereby
     *          closing the channel and setting the current thread's
     *          interrupt status
     *
     * @throws  IOException
     *          If some other I/O error occurs
     */
    public long write(ByteBuffer[] srcs, int offset, int length)
        throws IOException;


    /**
     * 从给定的缓冲区写入一个字节序列到此通道。
     *
     * <p> 调用这种形式的c.write(srcs)方法的行为方式与调用完全相同
     *
     * <blockquote><pre>
     * c.write(srcs, 0, srcs.length);</pre></blockquote>
     *
     * @param  srcs
     *         The buffers from which bytes are to be retrieved
     *
     * @return  The number of bytes written, possibly zero
     *
     * @throws  NonWritableChannelException
     *          If this channel was not opened for writing
     *
     * @throws  ClosedChannelException
     *          If this channel is closed
     *
     * @throws  AsynchronousCloseException
     *          If another thread closes this channel
     *          while the write operation is in progress
     *
     * @throws  ClosedByInterruptException
     *          If another thread interrupts the current thread
     *          while the write operation is in progress, thereby
     *          closing the channel and setting the current thread's
     *          interrupt status
     *
     * @throws  IOException
     *          If some other I/O error occurs
     */
    public long write(ByteBuffer[] srcs) throws IOException;

}
